home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 2003 August / MW 8 2003 CD1.iso / Inside Macworld / Product News / gimp-1.2.4.sit / gimp-1.2.4 / devel-docs / libgimp / sgml / gimpenv.sgml < prev    next >
Encoding:
Text File  |  2003-05-20  |  11.0 KB  |  257 lines
  1. <refentry id="libgimp-gimpenv" revision="19 Jan 2001">
  2. <refmeta>
  3. <refentrytitle>gimpenv</refentrytitle>
  4. <manvolnum>3</manvolnum>
  5. <refmiscinfo>LIBGIMP Library</refmiscinfo>
  6. </refmeta>
  7.  
  8. <refnamediv>
  9. <refname>gimpenv</refname><refpurpose>Functions to access the GIMP environment.</refpurpose>
  10. </refnamediv>
  11.  
  12. <refsynopsisdiv><title>Synopsis</title>
  13. <synopsis>
  14.  
  15.  
  16.  
  17. <link linkend="gchar">gchar</link>*      <link linkend="gimp-directory">gimp_directory</link>                  (void);
  18. <link linkend="gchar">gchar</link>*      <link linkend="gimp-personal-rc-file">gimp_personal_rc_file</link>           (<link linkend="gchar">gchar</link> *basename);
  19. <link linkend="gchar">gchar</link>*      <link linkend="gimp-data-directory">gimp_data_directory</link>             (void);
  20. <link linkend="gchar">gchar</link>*      <link linkend="gimp-sysconf-directory">gimp_sysconf_directory</link>          (void);
  21. <link linkend="gchar">gchar</link>*      <link linkend="gimp-gtkrc">gimp_gtkrc</link>                      (void);
  22. <link linkend="GList">GList</link>*      <link linkend="gimp-path-parse">gimp_path_parse</link>                 (<link linkend="gchar">gchar</link> *path,
  23.                                              <link linkend="gint">gint</link> max_paths,
  24.                                              <link linkend="gboolean">gboolean</link> check,
  25.                                              <link linkend="GList">GList</link> **check_failed);
  26. void        <link linkend="gimp-path-free">gimp_path_free</link>                  (<link linkend="GList">GList</link> *path);
  27. <link linkend="gchar">gchar</link>*      <link linkend="gimp-path-to-str">gimp_path_to_str</link>                (<link linkend="GList">GList</link> *path);
  28. <link linkend="gchar">gchar</link>*      <link linkend="gimp-path-get-user-writable-dir">gimp_path_get_user_writable_dir</link> (<link linkend="GList">GList</link> *path);
  29. </synopsis>
  30. </refsynopsisdiv>
  31.  
  32.  
  33.  
  34.  
  35.  
  36. <refsect1>
  37. <title>Description</title>
  38. <para>
  39. A set of functions to find the locations of GIMP's data directories and
  40. configuration files.
  41. </para>
  42. </refsect1>
  43.  
  44. <refsect1>
  45. <title>Details</title>
  46. <refsect2>
  47. <title><anchor id="gimp-directory">gimp_directory ()</title>
  48. <programlisting><link linkend="gchar">gchar</link>*      gimp_directory                  (void);</programlisting>
  49. <para>
  50. Returns the user-specific GIMP settings directory. If the environment 
  51. variable GIMP_DIRECTORY exists, it is used. If it is an absolute path, 
  52. it is used as is.  If it is a relative path, it is taken to be a 
  53. subdirectory of the home directory. If it is relative path, and no home 
  54. directory can be determined, it is taken to be a subdirectory of
  55. <link linkend="gimp-data-directory">gimp_data_directory</link>().
  56. </para>
  57. <para>
  58. The usual case is that no GIMP_DIRECTORY environment variable exists, 
  59. and then we use the GIMPDIR subdirectory of the home directory. If no 
  60. home directory exists, we use a per-user subdirectory of
  61. <link linkend="gimp-data-directory">gimp_data_directory</link>().
  62. In any case, we always return some non-empty string, whether it
  63. corresponds to an existing directory or not.
  64. </para>
  65. <para>
  66. The returned string is allocated just once, and should *NOT* be
  67. freed with <link linkend="g-free">g_free</link>().</para>
  68. <para>
  69.  
  70. </para><informaltable pgwide=1 frame="none" role="params">
  71. <tgroup cols="2">
  72. <colspec colwidth="2*">
  73. <colspec colwidth="8*">
  74. <tbody>
  75. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The user-specific GIMP settings directory.
  76. </entry></row>
  77. </tbody></tgroup></informaltable></refsect2>
  78. <refsect2>
  79. <title><anchor id="gimp-personal-rc-file">gimp_personal_rc_file ()</title>
  80. <programlisting><link linkend="gchar">gchar</link>*      gimp_personal_rc_file           (<link linkend="gchar">gchar</link> *basename);</programlisting>
  81. <para>
  82. Returns the name of a file in the user-specific GIMP settings directory.
  83. </para>
  84. <para>
  85. The returned string is allocated dynamically and *SHOULD* be freed
  86. with <link linkend="g-free">g_free</link>() after use.</para>
  87. <para>
  88.  
  89. </para><informaltable pgwide=1 frame="none" role="params">
  90. <tgroup cols="2">
  91. <colspec colwidth="2*">
  92. <colspec colwidth="8*">
  93. <tbody>
  94. <row><entry align="right"><parameter>basename</parameter> :</entry>
  95. <entry> The basename of a rc_file.
  96. </entry></row>
  97. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The name of a file in the user-specific GIMP settings directory.
  98. </entry></row>
  99. </tbody></tgroup></informaltable></refsect2>
  100. <refsect2>
  101. <title><anchor id="gimp-data-directory">gimp_data_directory ()</title>
  102. <programlisting><link linkend="gchar">gchar</link>*      gimp_data_directory             (void);</programlisting>
  103. <para>
  104. Returns the top directory for GIMP data. If the environment variable 
  105. GIMP_DATADIR exists, that is used.  It should be an absolute pathname.
  106. Otherwise, on Unix the compile-time defined directory is used.  On
  107. Win32, the installation directory as deduced from the executable's
  108. name is used.
  109. </para>
  110. <para>
  111. The returned string is allocated just once, and should *NOT* be
  112. freed with <link linkend="g-free">g_free</link>().</para>
  113. <para>
  114.  
  115. </para><informaltable pgwide=1 frame="none" role="params">
  116. <tgroup cols="2">
  117. <colspec colwidth="2*">
  118. <colspec colwidth="8*">
  119. <tbody>
  120. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The top directory for GIMP data.
  121. </entry></row>
  122. </tbody></tgroup></informaltable></refsect2>
  123. <refsect2>
  124. <title><anchor id="gimp-sysconf-directory">gimp_sysconf_directory ()</title>
  125. <programlisting><link linkend="gchar">gchar</link>*      gimp_sysconf_directory          (void);</programlisting>
  126. <para>
  127. Returns the top directory for GIMP config files. If the environment
  128. variable GIMP_SYSCONFDIR exists, that is used.  It should be an
  129. absolute pathname.  Otherwise, on Unix the compile-time defined
  130. directory is used.  On Win32, the installation directory as deduced
  131. from the executable's name is used.
  132. </para>
  133. <para>
  134. The returned string is allocated just once, and should *NOT* be
  135. freed with <link linkend="g-free">g_free</link>().</para>
  136. <para>
  137.  
  138. </para><informaltable pgwide=1 frame="none" role="params">
  139. <tgroup cols="2">
  140. <colspec colwidth="2*">
  141. <colspec colwidth="8*">
  142. <tbody>
  143. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The top directory for GIMP config files.
  144. </entry></row>
  145. </tbody></tgroup></informaltable></refsect2>
  146. <refsect2>
  147. <title><anchor id="gimp-gtkrc">gimp_gtkrc ()</title>
  148. <programlisting><link linkend="gchar">gchar</link>*      gimp_gtkrc                      (void);</programlisting>
  149. <para>
  150. Returns the name of the GIMP's application-specific gtkrc file.
  151. </para>
  152. <para>
  153. The returned string is allocated just once, and should *NOT* be
  154. freed with <link linkend="g-free">g_free</link>().</para>
  155. <para>
  156.  
  157. </para><informaltable pgwide=1 frame="none" role="params">
  158. <tgroup cols="2">
  159. <colspec colwidth="2*">
  160. <colspec colwidth="8*">
  161. <tbody>
  162. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The name of the GIMP's application-specific gtkrc file.
  163. </entry></row>
  164. </tbody></tgroup></informaltable></refsect2>
  165. <refsect2>
  166. <title><anchor id="gimp-path-parse">gimp_path_parse ()</title>
  167. <programlisting><link linkend="GList">GList</link>*      gimp_path_parse                 (<link linkend="gchar">gchar</link> *path,
  168.                                              <link linkend="gint">gint</link> max_paths,
  169.                                              <link linkend="gboolean">gboolean</link> check,
  170.                                              <link linkend="GList">GList</link> **check_failed);</programlisting>
  171. <para>
  172. </para>
  173. <para>
  174.  
  175. </para><informaltable pgwide=1 frame="none" role="params">
  176. <tgroup cols="2">
  177. <colspec colwidth="2*">
  178. <colspec colwidth="8*">
  179. <tbody>
  180. <row><entry align="right"><parameter>path</parameter> :</entry>
  181. <entry> A list of directories separated by <link linkend="G-SEARCHPATH-SEPARATOR-CAPS">G_SEARCHPATH_SEPARATOR</link>.
  182. </entry></row>
  183. <row><entry align="right"><parameter>max_paths</parameter> :</entry>
  184. <entry> The maximum number of directories to return.
  185. </entry></row>
  186. <row><entry align="right"><parameter>check</parameter> :</entry>
  187. <entry> <link linkend="TRUE-CAPS">TRUE</link> if you want the directories to be checked.
  188. </entry></row>
  189. <row><entry align="right"><parameter>check_failed</parameter> :</entry>
  190. <entry> Returns a <link linkend="GList">GList</link> of path elements for which the
  191. check failed. Each list element is guaranteed
  192. to end with a <link linkend="G-PATH-SEPARATOR-CAPS">G_PATH_SEPARATOR</link>.
  193. </entry></row>
  194. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> A <link linkend="GList">GList</link> of all directories in <parameter>path</parameter>. Each list element
  195. is guaranteed to end with a <link linkend="G-PATH-SEPARATOR-CAPS">G_PATH_SEPARATOR</link>.
  196. </entry></row>
  197. </tbody></tgroup></informaltable></refsect2>
  198. <refsect2>
  199. <title><anchor id="gimp-path-free">gimp_path_free ()</title>
  200. <programlisting>void        gimp_path_free                  (<link linkend="GList">GList</link> *path);</programlisting>
  201. <para>
  202. This function frees the memory allocated for the list and it's strings.</para>
  203. <para>
  204.  
  205. </para><informaltable pgwide=1 frame="none" role="params">
  206. <tgroup cols="2">
  207. <colspec colwidth="2*">
  208. <colspec colwidth="8*">
  209. <tbody>
  210. <row><entry align="right"><parameter>path</parameter> :</entry>
  211. <entry> A list of directories as returned by <link linkend="gimp-path-parse">gimp_path_parse</link>().
  212. </entry></row>
  213. </tbody></tgroup></informaltable></refsect2>
  214. <refsect2>
  215. <title><anchor id="gimp-path-to-str">gimp_path_to_str ()</title>
  216. <programlisting><link linkend="gchar">gchar</link>*      gimp_path_to_str                (<link linkend="GList">GList</link> *path);</programlisting>
  217. <para>
  218. </para>
  219. <para>
  220.  
  221. </para><informaltable pgwide=1 frame="none" role="params">
  222. <tgroup cols="2">
  223. <colspec colwidth="2*">
  224. <colspec colwidth="8*">
  225. <tbody>
  226. <row><entry align="right"><parameter>path</parameter> :</entry>
  227. <entry> A list of directories as returned by <link linkend="gimp-path-parse">gimp_path_parse</link>().
  228. </entry></row>
  229. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> A searchpath string separated by <link linkend="G-SEARCHPATH-SEPARATOR-CAPS">G_SEARCHPATH_SEPARATOR</link>.
  230. </entry></row>
  231. </tbody></tgroup></informaltable></refsect2>
  232. <refsect2>
  233. <title><anchor id="gimp-path-get-user-writable-dir">gimp_path_get_user_writable_dir ()</title>
  234. <programlisting><link linkend="gchar">gchar</link>*      gimp_path_get_user_writable_dir (<link linkend="GList">GList</link> *path);</programlisting>
  235. <para>
  236. Note that you have to <link linkend="g-free">g_free</link>() the returned string.</para>
  237. <para>
  238.  
  239. </para><informaltable pgwide=1 frame="none" role="params">
  240. <tgroup cols="2">
  241. <colspec colwidth="2*">
  242. <colspec colwidth="8*">
  243. <tbody>
  244. <row><entry align="right"><parameter>path</parameter> :</entry>
  245. <entry> A list of directories as returned by <link linkend="gimp-path-parse">gimp_path_parse</link>().
  246. </entry></row>
  247. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The first directory in <parameter>path</parameter> where the user has write permission.
  248. </entry></row>
  249. </tbody></tgroup></informaltable></refsect2>
  250.  
  251. </refsect1>
  252.  
  253.  
  254.  
  255.  
  256. </refentry>
  257.